<%#
# To change this template, choose Tools | Templates
# and open the template in the editor.
%>
<div class="intro" xmlns="http://www.w3.org/1999/html">
  <h1>API documentation</h1>
  <p>
  <%= t 'api.description' %>
  </p>
</div>

<br/>
<div class="row">

  <h3 style="background-color: #D9ECE4;"> Data collecting API </h3>
  <p>We describe here the process to feed the noisetube server of pollution data.</p>
  <ul>
    <li>1/ Creating a new session of measurement, <em>&quot;a track&quot;</em>:<br />
      http://www.noisetube.net/api/newsession?key={myapikey} </li>
  </ul>
  <ul>
    <li>2/ Adding exposure data of a citizen to his/her  current trace:
      <p align="left"><em>example: </em>http://www.noisetube.net/api/update?key=myapikey&amp;l=geo:12.23,2.12&amp;tag=klaxon&amp;db=56</p>
      <div align="left">where: </div>
        <table cellpadding="4" cellspacing="4" id="zebra-rows">
          <tr>
            <td bgcolor="#D9ECE4"><strong>Parameters</strong></td>
            <td bgcolor="#D9ECE4"><strong>Description</strong></td>
            <td bgcolor="#D9ECE4"><strong>Format </strong></td>
            <td bgcolor="#D9ECE4"><strong>Required </strong></td>
          </tr>
          <tr>
            <td>key</td>
            <td>the API key of the submitting user</td>
            <td>(mixed characters)</td>
            <td>x</td>
          </tr>
          <tr class="odd">
            <td>db</td>
            <td>loudness in dB(A)</td>
            <td>an integer between 30 to 110</td>
            <td>x</td>
          </tr>
          <tr>
            <td valign="top">l</td>
            <td>Geographical point in which measurements were made</td>
            <td><p>geo:lat,lng
              (e.g. l=geo:11.54,48.142) </p>
              </td>
            <td>&nbsp;</td>
          </tr>
          <tr class="odd">
            <td>tag</td>
            <td>tags associated to the measurements (comma separated)</td>
            <td>free text</td>
            <td>&nbsp;</td>
          </tr>
        </table>

      <br />
    </li>
  </ul>
  <ul>
    <li>3/ Ends the trace (to process the data on the server - <b>important</b>):<br />
      http://www.noisetube.net/api/endsesssion?key={myapikey}</li>
  </ul>
  <p align="center"><em>That's it! You have created a trace that  will be published and sharable through the website after its processing.</em></p>

  <hr/>

  <h3  style="background-color: #D9ECE4;">Access to the data commons API</h3>

  <p>Here we describe the API functions to track or get raw collected data</p>
  <h3>Function: api/search
  </h3>
  <p><strong>Description: </strong>Returns the last measurements (max. 500) that match the specified criteria:</p>
  <table  cellpadding="4" cellspacing="4" id="zebra-rows">
    <tr>
      <td bgcolor="#D9ECE4"><strong>Parameters</strong></td>
      <td bgcolor="#D9ECE4"><strong>Description</strong></td>
      <td bgcolor="#D9ECE4"><strong>Format </strong></td>
      <td bgcolor="#D9ECE4"><strong>Required </strong></td>
    </tr>
    <tr>
      <td>key</td>
      <td>API key belonging to the user making the request</td>
      <td>(mixed characters)</td>
      <td>x</td>
    </tr>
    <tr class="odd">
      <td>user</td>
      <td>ID or username of the user associated with the measurements</td>
      <td>&nbsp;</td>
      <td>&nbsp;</td>
    </tr>
    <tr>
      <td>tag</td>
      <td>tags associated with the measurements</td>
      <td>string (comma separated tags)</td>
      <td>&nbsp;</td>
    </tr>
    <tr class="odd">
      <td valign="top">city</td>
      <td>ID of the city where measurements were made</td>
      <td> integer </td>
      <td>&nbsp;</td>
    </tr>
    <tr>
      <td>since</td>
      <td>measurements made from this date (updated)</td>
      <td>W3C datetime format: <br />
        YYYY-MM-DDThh:mm:ss</td>
      <td></td>
    </tr>
    <tr class="odd">
      <td>until</td>
      <td>measurements made to this date (updated)</td>
      <td>W3C datetime format: <br />
        YYYY-MM-DDThh:mm:ss</td>
      <td></td>
    </tr>
    <tr>
      <td valign="top">box</td>
      <td>Location (as bounding box) </td>
      <td>lat1,lng1, lat2,lng2 e.g. box=4.404144,50.816846,4.38921,50.825305</td>
      <td></td>
    </tr>

    <tr class="odd">
      <td valign="top" >dbmax</td>
      <td> maximum decibel value</td>
      <td>integer</td>
      <td>&nbsp;</td>
    </tr>
    <tr>
      <td valign="top">dbmin</td>
      <td> minimum decibel value</td>
      <td>integer</td>
      <td>&nbsp;</td>
    </tr>
  </table>
  <p/>
  <h4>Examples</h4>
  <ul>
    <li>The last 100th measurements in a city<br />
      http://www.noisetube.net/api/search.json?key={apikey}&amp;city={cityID}&amp;max=100</li>
    <li>All the measurements tagged with &quot;neighbour&quot; in the city ID<br />
      http://www.noisetube.net/api/search.json?key={apikey}&amp;tag=neighbour&amp;city={cityID} </li>
    <li>All the measurements &gt;80 dB(a) in a given geographical area<br />
      http://www.noisetube.net/api/search.json?key={apikey}&amp;geo=11.54,48.142,11.5439,48.1454&amp;dbmin=80 // </li>
  </ul>
  <br/>
  <h4>JSON Return:<br/>
  </h4>
  <p>dataset=[{&quot;lat&quot;:48.8536,&quot;lng&quot;:2.38021,&quot;tags&quot;:[],&quot;date&quot;:1240213058000,&quot;l&quot;:68},<br />
    {&quot;lat&quot;:48.8536,&quot;lng&quot;:2.38021,&quot;tags&quot;:[],&quot;date&quot;:1240213067000,&quot;l&quot;:66},<br />
    {&quot;lat&quot;:48.8536,&quot;lng&quot;:2.38021,&quot;tags&quot;:[&quot;colleague&quot;],&quot;date&quot;:1240213268000,&quot;l&quot;:57}]</p>

  <hr />

  <h3 style="background-color: #D9ECE4;">Your traces</h3>
  <p><%= t 'api.yourtraces.description' %></p>

  <p> http://www.noisetube.net/api/traces?key={yourkey}&traces={traceid}.json </p>
  <h4>Description:</h4>
  Give the the measures associated to the trace with the id {trace.id} of the user {user.id}
  <br /><br />
  <h4>Examples:</h4>
  http://www.noisetube.net/api/traces?key=yourkey&traceid=id // give the associated measures of the traces with ID=traceid<br />
  http://www.noisetube.net/users/nico/traces/last.json // give the last trace generated by the user
  <br /><br />
  <p><strong>JSON Return:</strong><br/></p>

  <p>dataset=[{&quot;lat&quot;:48.8536,&quot;lng&quot;:2.38021,&quot;tags&quot;:[],&quot;date&quot;:1240213058000,&quot;l&quot;:68},<br />
    {&quot;lat&quot;:48.8536,&quot;lng&quot;:2.38021,&quot;tags&quot;:[],&quot;date&quot;:1240213067000,&quot;l&quot;:66},<br />
    {&quot;lat&quot;:48.8536,&quot;lng&quot;:2.38021,&quot;tags&quot;:[&quot;colleague&quot;],&quot;date&quot;:1240213268000,&quot;l&quot;:57}]</p>
</div>